package org.apache.commons.graph.algorithms.visit

import org.apache.commons.graph.Graph

/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements.  See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership.  The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License.  You may obtain a copy of the License at
*
*   http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied.  See the License for the
* specific language governing permissions and limitations
* under the License.
*/

/**
 * A [GraphVisitHandler] controls the execution of breadth-first and depth-first search
 * algorithms in [Visit].
 */
interface GraphVisitHandler<V, E, G : Graph<V, E>, O> {
    /**
     * Performs operations on the input edge and determines the behavior of the visit algorithm
     * based on the return value:
     *
     *  * [VisitState.CONTINUE] continues the visit normally;
     *  * [VisitState.SKIP] continues the visit skipping the input edge;
     *  * [VisitState.ABORT] terminates the visit.
     *
     * @return the state of the visit after operations on the edge
     */
    fun discoverEdge(head: V, edge: E, tail: V): VisitState

    /**
     * Called at the beginning of breadth-first and depth-first search.
     */
    fun discoverGraph(graph: G)

    /**
     * Performs operations on the input vertex and determines the behavior of the visit algorithm
     * based on the return value:
     *
     *  * [VisitState.CONTINUE] continues the visit normally;
     *  * [VisitState.SKIP] continues the visit skipping the input vertex;
     *  * [VisitState.ABORT] terminates the visit.
     *
     * @return the state of the visit after operations on the vertex
     */
    fun discoverVertex(vertex: V): VisitState

    /**
     * Checks if the search algorithm should be terminated. Called after the search algorithm has finished
     * visiting the input edge.
     * @return [VisitState.ABORT] if the search algorithm should be terminated after visiting the input edge, [VisitState.CONTINUE] otherwise
     */
    fun finishEdge(head: V, edge: E, tail: V): VisitState

    /**
     * Called upon termination of the search algorithm.
     */
    fun finishGraph(graph: G)

    /**
     * Checks if the search algorithm should be terminated. Called after the search algorithm has finished
     * visiting the input vertex.
     * @return [VisitState.ABORT] if the search algorithm should be terminated after visiting the input vertex, [VisitState.CONTINUE] otherwise
     */
    fun finishVertex(vertex: V): VisitState

    /**
     * Invoked once the visit is finished.
     *
     * @return Value that will be returned by the visit
     */
    fun onCompleted(): O?
}
